\chapter{Tutorial}

\section{Interpreter}

Start up durexForth. If loaded successfully, it will greet you with a friendly \texttt{ok}. You have landed in the interpreter!

Let's warm it up a little. Enter \texttt{1} (followed by return). You have now put a digit on the stack. This can be verified by the command \texttt{.s}, which will print out the stack. Now enter \texttt{.} to pop the digit and print it to screen, followed by \texttt{.s} to verify that the stack is empty.

Now some arithmetics. \texttt{1000 a * .} will calculate $\$a \times \$1000$ and print the result on the screen. \texttt{6502 100 / 1- .} will calculate and print $(\$6502 / \$100) - 1$.

Let's define a word \texttt{bg} for setting the border color\ldots 

\begin{verbatim}
: bg d020 c! ;
\end{verbatim}

\texttt{0 bg}, \texttt{1 bg} and so on will let you set border color. Cool! Now let's head on to making our first ``real'' program\ldots

\section{Editor}

The editor (fully described in chapter \ref{editor}) is convenient for editing larger pieces of code. With it, you keep an entire source file loaded in RAM, and you can recompile and test it easily.

Start the editor by typing \texttt{s" foo" vi}.\footnote{Yes, the space should be between \texttt{s"} and \texttt{foo"}. The \texttt{s"} word creates a string by reading characters until it hits a \texttt{"}.}
It will try to open the (non-existant) file ``foo.'' After a little while you will be presented to the nice pink screen of the editor. 

To enter text, first press \texttt{i} to enter insert mode. This mode allows you to insert text into the buffer. You can see that it's active on the \texttt{I} that appears in the lower left corner.

This is a good start for making a program. But first, let's get rid of the junk we created in the last section. Enter:

\begin{verbatim}
forget bg
\end{verbatim}

\ldots and press $\leftarrow$ to leave insert mode. This line forgets the \texttt{bg} word that you defined in the last section, and everything defined after it. Let's try out if it works.

First, quit the editor by pressing \texttt{:q}. You should now be back in the interpreter screen. Verify that the word \texttt{bg} still exists by  entering \texttt{0 bg}, \texttt{1 bg} like you did before. Then, jump back to the editor using the command \texttt{fg} (foreground). You should return to your edit buffer with the lonely \texttt{forget bg} line.

Now, compile and run the buffer by pressing \texttt{F7}. You will be thrown out to the interpreter again. Entering \texttt{bg} should now give you the error \colorbox{yellow}{\texttt{bg?}}. Success --- we have forgotten the \texttt{bg} word. Now, get back into the editor with \texttt{fg} again.

Under \texttt{forget bg}, add the following lines:

\begin{verbatim}
: flash d020 c@ 1+ d020 c! recurse ;
flash
\end{verbatim}

\texttt{flash} will cycle the border color infinitely. Before trying it out, go up and change \texttt{forget bg} to \texttt{forget flash}. This makes sure you won't run out of RAM, no matter how many times you recompile the program. Now press \texttt{F7} to compile and run. If everything is entered right, you will be facing a wonderful color cycle.

To stop the program, press RESTORE to get to the interpreter. Then enter \texttt{fg} to get back into the editor. Let's see how we can factor the program to get something more Forth'y:

\begin{verbatim}
forget bg
: bg d020 ; # border color addr
: 1+c! dup c@ 1+ swap c! ; ( addr -- ) # inc addr by 1
: flash dup 1+c! recurse ; ( addr -- ) # inc addr forever
bg flash
\end{verbatim}

(Note: Parentheses are used for multi-line comments or describing arguments and return values. \texttt{\#} is used for single-line comments.)

Of course, it is a matter of taste which version you prefer. Press \texttt{F7} to see if the new version runs faster or slower.

\section{Assembler}

If you need to flash as fast as possible, use the assembler:

\begin{verbatim}
:asm flash
here @ # push curr addr
d020 inc,
jmp, # jmp to pushed addr
;asm
flash
\end{verbatim}

\texttt{:asm} and \texttt{;asm} define a code word, just like \texttt{:} and \texttt{;} define Forth words. Within a code word, you can use assembler mnemonics. 

Note: As the x register contains the durexForth stack depth, it is important that it remains unchanged at the end of the code word.

\section{Console I/O Example}

This piece of code reads from keyboard and sends back the chars to screen:

\begin{verbatim}
: init 0 linebuf c! ; # turn off key buffering
: foo init begin key emit again ;
foo
\end{verbatim}

\section{Configuring durexForth}

\subsection{Stripping Modules}

By default, durexForth boots up with all modules pre-compiled in RAM:

\begin{description}
\item[debug] Words for debugging.
\item[asm] The assembler.
\item[edit] The text editor.
\end{description}

To reduce RAM usage, you may make a stripped-down version of durexForth. Do this by following these steps:

\begin{enumerate}
\item Issue \texttt{forget modules} to forget all modules.
\item Optionally re-add the \texttt{modules} marker with \texttt{: modules ;}
\item One by one, load the modules you want included with your new Forth. (E.g. \texttt{s" debug" load})
\item Save the new system with e.g. \texttt{s" acmeforth" save-forth}.
\end{enumerate}

\subsection{Custom Start-Up}

You may launch a word automatically at start-up by setting the variable \texttt{start} to the execution token of the word.  Example: \texttt{loc megademo >cfa start !}

To save the new configuration to disk, use \texttt{save-forth}.

\section{How to Learn More}

\subsection{Internet Resources}

\subsubsection{Books and Papers}

\begin{itemize}
\item \href{http://www.forth.com/starting-forth/}{Starting Forth}
\item \href{http://thinking-forth.sourceforge.net/}{Thinking Forth}
\item \href{http://www.bradrodriguez.com/papers/}{Moving Forth: a series on writing Forth kernels}
\item \href{http://www.csbruce.com/~csbruce/cbm/transactor/v7/i5/p058.html}{Blazin' Forth --- An inside look at the Blazin' Forth compiler}
\item \href{http://dobbscodetalk.com/index.php?option=com_myblog&show=In-this-1980-article-from-Byte-Charles-Moore-recounts-the-creation-of-Forth..html&Itemid=29}{The Evolution of FORTH, an unusual language}
\item \href{http://galileo.phys.virginia.edu/classes/551.jvn.fall01/primer.htm}{A Beginner's Guide to Forth}
\end{itemize}

\subsubsection{Other Forths}

\begin{itemize}
\item \href{http://www.colorforth.com/cf.html}{colorForth}
\item \href{http://www.annexia.org/forth}{JONESFORTH}
\item \href{http://colorforthray.info/}{colorForthRay.info --- How\_to: with Ray St. Marie}
\end{itemize}

\subsection{Other}

\begin{itemize}
\item \href{http://code.google.com/p/durexforth/}{durexForth source code}
\end{itemize}

Quality coders may contact a Durex representative for assistance.
